/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			main.h
  \date			Aug 2011
  \author		TNick

  \brief		Contains global definitions for application


  Copyright (c) 2011, Nicu Tofan
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
	* Redistributions of source code must retain the above copyright
	  notice, this list of conditions and the following disclaimer.
	* Redistributions in binary form must reproduce the above copyright
	  notice, this list of conditions and the following disclaimer in the
	  documentation and/or other materials provided with the distribution.
	* Neither the name of the copyright holder nor the
	  names of its contributors may be used to endorse or promote products
	  derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL NICU TOFAN BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

/**
	\mainpage	EquTemper source code documentation

The project uses Qt to became a platform-independent equation editor.


\section documentation Documentation
Source code documentation, that was automatically generated using
<a href="http://www.doxygen.org">Doxygen</a>, is accessible to be
<a href="https://equtemper.googlecode.com/svn/trunk/doc/html/index.html">browsed online</a>.

<a href="https://code.google.com">Google code</a> also provides the project with
<a href="https://code.google.com/p/equtemper/wiki/MainPage">a wiki</a>,
where development guiding lines are lined up.

User documentation in html format, enhanced with screen captions and
easy-to-read text, shall be placed online, too, as soon as first
version is available for download.


\section downloads Downloads
Binary distributions shall be available in
<a href="https://code.google.com/p/equtemper/downloads/list">dedicated section</a>.
As indicated in
<a href="https://code.google.com/p/equtemper/wiki/SiteBluePrint">Site blueprint</a>,
<a href="https://code.google.com/p/equtemper/downloads/list">downloads section</a>
is organised in folders, each having the name of the version that they host.


\section src_code Source code
Each version will make it's source code available as various types of archives.
Also, the repository may be
<a href="https://code.google.com/p/equtemper/source/checkout">checked out</a> using
<a href="http://subversion.tigris.org">svn</a> or it may be
<a href="https://code.google.com/p/equtemper/source/browse/#svn%2Ftrunk">browsed online</a>.


\section user_support Bug reports. Feature requests. Ideas.
To complain about something please use the
<a href="https://code.google.com/p/equtemper/issues/list">issues section</a>.
A goggle group or a forum may be set-up later, as needed.


\section contrib Contributions
These are highly welcomed. Please browse through
<a href="https://code.google.com/p/equtemper/source/browse/#svn%2Ftrunk">source code</a>
to familiarise yourself with it, first, then drop me
<a href="https://sites.google.com/site/tnickweb/home">an e-mail</a>.

<hr>
Step to \subpage sp_src_idx "an overview of source code" or see the
\subpage future_plans "things that need to be done."
A separate page for \subpage ddhc_main_page "debugging module" describes it's
implementation and usage.


\page sp_src_idx An overview of source code

This page attempts to give an overview of the source code and to give
the new coder a place to start. The documentation is created using
 <a href="http://www.doxygen.org">Doxygen</a> and, as such, has a couple
standard features (
<a href="annotated.html">class list</a>,
<a href="files.html">file list</a>,
<a href="todo.html">todo page</a>). Also, class inheritance page, both in
<a href="hierarchy.html">text form</a> and in
<a href="inherits.html">graphical form</a>, provide and insight into the
way source code is organised. However, this page will attempt to describe
the classes based on their logical relations and intended purpose.


\section class_gen Generic classes
Only two related clases fell into this category right now: CC_L2D and CC_HDL2D.
These provide a simple implementation for a linked list, where CC_HDL2D is
the header that may be embedded inside other classes and CC_L2D is the class
that needs to be inherited by the classes that are to be linked. CC_HDL2D only
stores a count of items it hosts and the pointer to the first kid, while
CC_L2D stores pointers to previous nad next items; no link is made to
CC_HDL2D that hosts it, so classes need to implement links to parents themselves.


\section class_gui Graphical User Interface (GUI) classes
The cental widget is represented by the MainWindow class. It's functionality
is divided into modules addressing specific issues:
- Generic units
	- MW_BasicMdi is the logic unit responsible for providing common functionality
	for using Multiple Document Interface (MDI); it handles the list of visible
	docuiments available in the Windows menu and is able to get a pointer to the
	active MdiChild document.
	- MW_BasicSlots groups event handlers that are most likely to be used
	by any simple GUI application, ranging from simple file opperations (new, open,
	close) to editing opperations (cut, copy, paste, delete) to help handlers.
	- MW_RecentFiles it is able to load a previously saved list of files and to
	show it in designated menu. Also able to direct the application into loading
	a recent file.
	- MW_UiTempl encapsulates the look and feel of a GUI. Allows the user to
	change the apparence of all widgets based on predefined templates.
	- MW_StyleSheets allows to further customise of the apparence of widgets;
	this functionality is based on HTML-like
	<a href="http://doc.qt.nokia.com/latest/stylesheet.html">style sheets </a>.
- Specific units
	- MW_SheetSlots manages signals that are intended to reach the active sheet
	or active viewport in active sheet in current MDI document.

The panels inside MDI area are all MdiChild instances. At file level (and,
possiblly, at class level at some point in the future) the functionality is
divided in two more logical parts beside the main:
- mdic_basic.h file has functionality that gives a target to MW_BasicSlots and
is mostly related to file and edit opperations.
- mdic_viewport.h supports the use of mustiple span-able viewports and zoom and
rotation for current viewport.


\section sheets	Sheets. Viewports.
The architecture is similar to that used in Qt, where the in-memory storage is
isolated in a separate class, with other classes being able to represent
contained data.

ETSheet class is a logical root for all elements contained in a document. It
inherits from
<a href="http://doc.qt.nokia.com/latest/qgraphicsscene.html">QGraphicsScene</a>
most of it's functionality. Exactly one ETSheet instance is associated with
a MdiChild instance.

ETSheetView class (the viewport) is able to represent the content of an ETSheet.
It drives it's functionality from
<a href="http://doc.qt.nokia.com/latest/qgraphicsview.html">QGraphicsView</a>.
Each MdiChild instance may contain one or more ETSheetView viewports, but
they will all look at the same scene.


\section items_subitems	Items and sub-items
The items are instances of classes that inherit from
<a href="http://doc.qt.nokia.com/latest/qgraphicsitem.html">QGraphicsItem</a> and
the names always start with \b ETI_.
These are hosted and managed by ETSheet class and are selectable and movable
by the user. Currently, there are two types of items:
- ETI_CplxTxt, which is a host for ETSubItem sub-items and represents a
complex text (that may be an equation or formula);
- ETI_MTxt, extending the functionality of
<a href="http://doc.qt.nokia.com/latest/qgraphicstextitem.html">QGraphicsTextItem</a>
and, as such, being able to display a formatted chunk of text.

The sub-items are instances of classes that inherit from ETSubItem and have
names that always start with \b ETSI_ . These are
hosted in an ETI_CplxTxt instance and may form a complex tree, as each sub-item
may contain another sub-items on it's turn. The types of sub-items that are
currently defined ae listed below:
- ETSI_Root: sub-item able to host a row of horizontal sub-items; this is one
of the building blocks used to create more complex sub-items
- ETSI_SText: simple sub-item capable of displayng a string; another building
block for more complex sub-items
- ETSI_Fract: sub-item displaying a fraction; consists of two ETSI_Root sub-items
- ETSI_HText: presents a central text and has six other ETSI_Root arround it
- ETSI_Integ: sub-item representing an integral
- ETSI_Lim: sub-item presenting a limit
- ETSI_LogicAc: sub-item able to display a logical if-elseif-else component
- ETSI_Matrix: sub-item presenting a matrix or a determinant
- ETSI_Radic: sub-item that will display a radical
- ETSI_Sum: sub-item that will display a sum


\section vp_commands	Viewport commands
Each view is able to maintain a command independent of other views.
Having multiple views looking at a single scene means that there may
be multiple commands running against same scene.

Commands are instances of classes that inherit from ETVpCommand and, basically,
require the caller to create an instance of the command, initialise the options,
and pass the instance to ETSheetView::startCommand().

Following commands are defined so far:
- ETVpCmd_EditSubI: starts the editing of an sub-item
- ETVpCmd_NewSubI: creates a new sub-item
- ETVpCmd_NewTopElem: creates a new item


\section undo_redo	Undo and redo
This functionality is implemented at sheet level, meaning that all sheets
have the ability to keep a chain of changes independent of other sheets that may
be opened at the same time.

The class that implements the interface used by other components is
ETUndoHead and an instance is embedded in each ETSheet. Undo and redo
opperations are all chained in a single row, with a pointer walking the chain
according to the commands it recieves.

Each unitary opperation is an instance of a class that inherits from ETUndoElem.
This abstract class provides the means to access the instances and send them
undo / redo commands independent of the underlying opperation.


\section save_load	Saving and loading to / from file
There is no separate class that does this opperations. Instead, the
functionality is embedded inside ETSheet via ETSheet::saveXMLFile() and
ETSheet::loadXMLFile(). As the name implies the XML format is used in
saving / loading the file and
<a href="http://doc.qt.nokia.com/latest/qtxml.html">QtXml Module</a>
is used to accomplish the tasks.

The format of the file that is saved follows the guidance in
<a href="https://code.google.com/p/equtemper/source/browse/trunk/doc/example.xml">
example.xml</a> that is located in
<a href="https://code.google.com/p/equtemper/source/browse/trunk/doc">doc</a>
subfolder.

@todo current implementation does not check for a version. Do that.

<hr>
Step to next page: \ref future_plans "things that need to be done." or go to
previous page: <a href="index.html">documentation home</a>




\page future_plans Things to be implemented

This page lists the things that need to be done and that have no othaer place
to live in. The <a href="todo.html">todo page</a>) lists things to be
implemented that already have a defined place.


\section sect_calc_eng	Computational engine
A way to evaluate the values and to highlite the parts that can't be evaluated.
Default flow of execution marked with arrows that the user may edit.


\section sect_find_replace	Search and replace
Name said it all. Tied with the \ref sect_var_high "highlite section".


\section sect_var_high	Names highlite
Highlite the name of:
- the variable under the mouse on mouse move
- choosen variable during comman
inside entire sheet. Navigate to previous / next occurence.

The highlite must be viewport based, so that highliting an expression in a
viewport does not show it highlited in another.


\section sect_parser	Parser
The parser needs to be able to parse:
- c/c++ expressions
- tex expressions
- what else?

To support the interaction with the parser, the user shall be presented with a
text box embedded in the viewport / outside of it where it may type the entire
text without being disturbed by constant re-arranging that occurs inmain editor.
This may be presented as an option to replace the default behaviour and as a
separate command.


\section sect_Viewports	Viewports
Highlite the current viewport inside MdiChild


\section sect_imports	Imports
Place import statement (visible or not, according to user's choice) that
inherit a set of formulas. Create online repository.


\section sect_docum	List of functions / variables. Documentation
A pop-up / docked panel shall present the list of known tokens (from all
imported sheets  or only from this one) grouped in various ways and present:
- icons / color codes to tell the type of the token
- the sheet where they originated.

Optionally, the occurences may be highlited when a list entry is selected.

Each token may have an associated description. A popup / docked window may
track the mouse or the selection and display the brief documentation for that
token. Extensive documentation / links to wikipedia pages need to have their
own browser, perhaps in MDI area. Options should enable the user to open links
in it's default browser.


\section sect_plugins	Plug-ins. Scripting.
It is vital to let the advanced user use extended capabilities. This may be
accomplished using a plug-in system based on dynamic loading of the libraries
and (at least) a scripting system.


\section sect_items		Items
Using flexible interface provided by the
<a href="http://doc.qt.nokia.com/latest/qgraphicsscene.html>QGraphicsScene</a>
a large variety of items may be created inside the sheet. Underlying
engine is OpenGL, so 2D drawing capabilities are at fingertips. Elements
like charts, animations, ... have to be implemented.


\section sect_various		Various

- be able to display sub-Items with different settings
- simple / fancy display of graphics (image / line)
- text more read-able
- toolbar for apparence (font color background)
- window to show only current sub-item or item
- user un create sub-items
- scale individual elements
- clear formatting and autoadjust sizes
- printing
- cut copy paste xml based
- undo and redo
- user settings for all things
- draw order (front back front before after)
- decorated text; toolbar
- images as items
- convert to/from other notations (latex web)
- settings for wheel (zoom scroll)
- copy / save as image
- plug-ins; script as plug-in



<hr>
Step to next page: <a href="hierarchy.html">class herarchy</a> or go to
previous page: \ref sp_src_idx "An overview of the sourcecode"




*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __MAIN_INC__
#define __MAIN_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  DEFINITIONS    --------------------------------------------------------- */

class       MainWindow;
class       QNetworkAccessManager;
class       QTimer;
class       QNetworkDiskCache;

/// the name of the application as a string
#define     APP_NAME                "equtemper"

/* uncomment following line to use QMutex instead of QReadWriteLock */
// #define PREFER_MUTEXES      1

/* uncomment following line to trace execution (output text to indicate code flow) */
#define     FOLLOW_EXECUTION     1

/// default time between two consecutive requests for pages
#define     DEFAULT_SEARCH_INTERVAL     10000

/* uncomment this to enable application wide debug features */
#define		APP_DEBUG			1


/// set to 1 to include dynamic debugger helper code; set to 0 to disable
#define		ENABLE_DDHC			0




#ifdef  FOLLOW_EXECUTION
#define TRACE_EXECUTION(a,b,c)     qDebug() << __FUNCTION__ << ": " << a << b << c
#else
#define TRACE_EXECUTION(a,b,c)
#endif


/* for each bug that is traced a specific name should be used; this way, when
the bug is finnaly removed, the verbrose debug messages may be
removed from code */
// #define		SPECIFIC_BUG	qDebug() << __FUNCTION__ <<
#define		LIST_BUG	qDebug() << __FUNCTION__ <<









/*  DEFINITIONS    ========================================================= */
//
//
//
//
/*  DATA    ---------------------------------------------------------------- */

/// hold pointer to main gui object in global variable for easy access
extern      MainWindow *                g_MW;
extern      QNetworkAccessManager *     l_manager ;
extern      QTimer *                    app_timer;
extern      QNetworkDiskCache *         main_cache ;

/*  DATA    ================================================================ */
//
//
//
//
/*  FUNCTIONS    ----------------------------------------------------------- */


/*  FUNCTIONS    =========================================================== */
//
//
//
//

#include	<debug/ddhc_main.h>

#endif // __MAIN_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
